Skip to main content

ACH Returns

This API allows clients to initiate an ACH Credit Return operation for a previously credited transaction. It also returns the status of the return request, along with updated account details and a unique process ID for tracking.

Method: POST​

{{URL}}/rpc/paymentv2

Example​

Request Parameters
ParameterDescription
methodString
RPC method name (e.g., ledger.ach.return)
idString
Unique ID for the request
payloadObject
referenceString
Unique reference ID of the return request
transactionTypeString
Must be "ACH_IN_CREDIT_RETURN"
transactionDateTimeString
Date and time of return request (format: YYYY-MM-DD HH:MM:SS)
channelString
Must be "ACH"
originalTransactionNumberString
Transaction number of the original incoming ACH credit
returnCodeString
Return Code (e.g., R01)
reasonString
Reason for the return
apiObject
credentialString
Basic (space) [("<Username>:<apiKey>") as Base64 encoded value] to be provided
Sample Value: "Basic bmF2eWEubitlbXBAbmV0eGQuY29tOmY1OWIwY2NlOTU4ZTQ1YTc4MGVhZWIzYWVjOWVjZDAx"
signatureString
Sign the request payload (params.payload) using private key.
Sample Value: "MEQCIAbpxHpdOyBEVlmxPYv7m4Z1OvWJJYw7g7u3GE3T9nmvAiBjKHckSvb1M6O4t7FeWsn2z9Y3dMeYn3HyX/k28ek/Dw=="
apiKeyString
API key is provided at the time of device registration.
Sample Value : "f59b0cce958e45a780eaeb3aec9ecd01"

Body​

'{
   "method": "ledger.ach.return",
   "id": "1",
   "params": {
    "payload": {
    "reference": "PL-TS-INR-000036",
    "transactionType": "ACH_IN_CREDIT_RETURN",
    "transactionDateTime": "2025-03-17 14:01:00",
    "channel": "ACH",
    "originalTransactionNumber": "QA00000001335030",
    "returnCode": "R01",
    "reason": "Insufficient Funds"
    },
    "api": {
    "credential": "{{Cred}}",
    "signature": "{{signature}}",
    "apiKey": "{{API}}"
    }
   }
 }'

Response: 200​

Response Parameters
ParameterDescription
apiObject
typeString
Acknowledgement type (e.g., ACH_IN_CREDIT_RETURN_ACK)
referenceString
Reference number generated for the return transaction
dateTimeString
Timestamp of the response
accountObject
accountIdString
Account identifier associated with the transaction
balanceCentsInteger
Account balance in cents
holdBalanceCentsInteger
Amount on hold in cents
statusString
Status of the account (e.g., ACTIVE)
transactionNumberString
Unique number assigned to the return transaction
transactionStatusString
Current status (e.g., PENDING, COMPLETED, FAILED)
transactionAmountCentsInteger
Amount returned in cents
originalRequestBase64String
Base64-encoded version of the original return request
processIdString
Internal process ID for traceability
headerObject
referenceString
Transaction reference
apiKeyString
Echoed API Key
signatureString
Echoed Signature
{
   "id": "1",
   "result": {
    "api": {
    "type": "ACH_IN_CREDIT_RETURN_ACK",
    "reference": "PL-TS-INR-000036",
    "dateTime": "2025-03-17 14:02:23"
    },
    "account": {
    "accountId": "200133255370754",
    "balanceCents": 2006127468,
    "holdBalanceCents": 45140,
    "status": "ACTIVE"
    },
    "transactionNumber": "QA00000001335033",
    "transactionStatus": "PENDING",
    "transactionAmountCents": 5500,
    "originalRequestBase64": "base64-encoded-original-payload",
    "processId": "PL25031701310017"
   },
   "header": {
    "reference": "PL-TS-INR-000036",
    "apiKey": "f54873cb58a6445c9e6825e75450f879",
    "signature": "MEYCIQDybl...dk3Ia"
   }
 }

ACH Return Codes​

ACH Return Codes
CodeDescription
R01Insufficient Funds
R02Account Closed
R03No Account / Unable to Locate Account
R04Invalid Account Number Structure
R05Unauthorized Debit to Consumer Account Using Corporate SEC Code
R06Returned per ODFI's Request
R07Authorization Revoked by Customer
R08Payment Stopped
R09Uncollected Funds
R10Customer Advises Not Authorized
R11Customer Advises Entry Not in Accordance with the Terms of the Authorization
R12Account Sold to Another DFI
R13Invalid ACH Routing Number
R14Representative Payee Deceased
R15Beneficiary or Account Holder Deceased
R16Account Frozen
R17File Record Edit Criteria / Entry with Invalid Account Number Initiated Under Questionable Circumstances
R18Improper Effective Entry Date
R19Amount Field Error
R20Non-Transaction Account
R21Invalid Company Identification
R22Invalid Individual ID Number
R23Credit Entry Refused by Receiver
R24Duplicate Entry
R25Addenda Error
R26Mandatory Field Error
R27Trace Number Error
R28Routing Number Check Digit Error
R29Corporate Customer Advises Not Authorized
R30RDFI Not Participant in Check Truncation Program
R31Permissible Return Entry (CCD and CTX only)
R32RDFI Non-Settlement
R33Return of XCK Entry
R34Limited Participation DFI
R35Return of Improper Debit Entry
R36Return of Improper Credit Entry
R37Source Document Presented for Payment
R38Stop Payment on Source Document
R39Improper Source Document / Amount Not Accurately Obtained from Source Document
R40Return of ENR Entry by Federal Government Agency
R41Invalid Transaction Code
R42Routing Number / Check Digit Error
R43Invalid DFI Account Number
R44Invalid Individual ID Number
R45Invalid Individual / Company Name
R46Invalid Representative Payee Indicator Code
R47Duplicate Enrollment
R50State Law Affecting RCK Acceptance
R51Item Related to RCK Entry is Ineligible or Improper
R52Stop Payment on Item Related to RCK Entry
R53Item and RCK Entry Presented for Payment
R61Misrouted Return
R62Return of Erroneous or Reversing Debit
R67Duplicate Return
R68Untimely Return
R69Field Error
R70Permissible Return Not Accepted / Not Requested by ODFI
R71Misrouted Dishonored Return
R72Untimely Dishonored Return

Error Codes​

Error Codes
Error CodeError Message
A107DUPLICATE_REFERENCE
A112INVALID_AMOUNT
A113INVALID_CHANNEL
A114CUSTOMER_NOT_FOUND
A116INVALID_API_KEY
A118TRANSACTION_REFERENCE_EMPTY
A122PROGRAM NOT FOUND
A123CREDITOR_ACCOUNT_TYPE_EMPTY
A126TRANSACTION_TYPE_EMPTY
A147TRANSACTION NOT FOUND
A157INVALID ACCOUNT NUMBER
A161DEBTOR ACCOUNT NOT FOUND
A166DEBTOR_ACCOUNT_TYPE_EMPTY
A167DEBTOR_ACCOUNT_ID_EMPTY
A169ACCOUNT NUMBER DOES NOT MATCH WITH API KEY
A172IDENTIFICATIONTYPE2 SHOULD BE EITHER SAVINGS OR CHECKING
A183PAYLOAD EMPTY
A184INVALID ORIGINAL TRANSACTION STATUS
A185TRANSACTION ALREADY REVERSED
A186CREDITOR FIRSTNAME REQUIRED
A187CREDITOR POSTAL ADDRESS ADDRESSLINE1 REQUIRED
A188CREDITOR POSTAL ADDRESS ZIPCODE REQUIRED
A189CREDITOR POSTAL ADDRESS COUNTRYCODE REQUIRED
A190CREDITOR CONTACT EITHER PRIMARYEMAIL OR PRIMARYPHONE REQUIRED
A191DEBTOR FIRSTNAME REQUIRED
A192DEBTOR POSTAL ADDRESS ADDRESSLINE1 REQUIRED
A193DEBTOR POSTAL ADDRESS ZIPCODE REQUIRED
A194DEBTOR POSTAL ADDRESS COUNTRYCODE REQUIRED
A195DEBTOR CONTACT EITHER PRIMARYEMAIL OR PRIMARYPHONE REQUIRED
A196DEBTOR USERTYPE REQUIRED
A197DEBTOR IDENTIFICATION REQUIRED
A198DEBTOR IDENTIFICATIONTYPE REQUIRED
A199CREDITOR USERTYPE REQUIRED
A200CREDITOR IDENTIFICATION REQUIRED
A201CREDITOR IDENTIFICATIONTYPE REQUIRED
A205INVALID_PROGRAM
A206INVALID_PRODUCT
A207PRODUCT_PROGRAM_CHANNEL SETTING NOT FOUND
A208ID EMPTY
A209APIKEY NOT FOUND
1111CREDITOR ACCOUNT NOT FOUND
1113CREDITOR NOT FOUND
1116TRANSACTION AMOUNT NOT FOUND
1117TRANSACTION CURRENCY NOT FOUND
1122CREDITOR ACCOUNT IDENTIFICATION TYPE NOT FOUND
1123CREDITOR ACCOUNT IDENTIFICATION TYPE2 NOT FOUND
1126DEBTOR ACCOUNT IDENTIFICATION TYPE NOT FOUND
1127PRODUCT NOT FOUND
1128PROGRAM NOT FOUND
1129CHANNEL NOT FOUND
1130TRANSACTION TYPE NOT FOUND
1131INVALID API KEY
2053INVALID_ACCOUNT_NUMBER
5019INSUFFICIENT BALANCE
9999INTERNAL ERROR
1001CARD HOLDER ALREADY EXISTS
1002INVALID CARDHOLDER FIRST NAME
1003INVALID CARDHOLDER PHONE NUMBER
1004INVALID CARDHOLDER ADDRESS LINE 1
1005INVALID CARDHOLDER CITY
1006INVALID CARDHOLDER STATE
UNAUTHORIZEDAccess Denied
INVALID_SIGNATUREInvalid Signature
NOT_FOUND_USER_DEVICEUser device not found
BAD_CREDENTIALInvalid Credential